HPAVC

home *** CD-ROM | disk | FTP | other *** search

/ HPAVC / HPAVC CD-ROM.iso / pc / POVHELP.ZIP / source / helpdata.doc < prev next >

Wrap

Text File | 1994-08-16 | 20.5 KB | 451 lines

/**************************************************************************** * HELPDATA.DOC - Version 1.0 - 4 July 1994 * * This document describes the format of the POVHELP database. * * from Persistence of Vision Raytracer * Copyright 1994 Persistence of Vision Team * Copyright 1994 Christopher J. Cason. *--------------------------------------------------------------------------- * NOTICE: This data file is provided so that users may experiment with * enhancements to POV-Ray and to port the software to platforms other * than those supported by the POV-Ray Team. There are strict rules under * which you are permitted to use this file. The rules are in the file * named POVLEGAL.DOC which should be distributed with this file. If * POVLEGAL.DOC is not available or for more info please contact the POV-Ray * Team Coordinator by leaving a message in CompuServe's Graphics Developer's * Forum. The latest version of POV-Ray may be found there as well. * * POV-Ray files may also be obtained from ftp.uwa.edu.au in pub/povray. * * This document was written in its entirety by Christopher J. Cason. * Its use is freely and permanently granted to the POV-Team and POV users * under the conditions specified in POVLEGAL.DOC. * * Author : C. J. Cason (cjcason@yarrow.wt.uwa.edu.au, CIS 100032,1644) * *****************************************************************************/ P O V - H E L P - D A T A B A S E F O R M A T ------------------------------------------------ This file is provided to encourage people to write custom help converters rather than taking an ASCII version of POVRAY.DOC and converting it manually. Once a converter has been released, whenever we change the docs, the converted versions can be re-generated easily. The intention is that this database be ported to other, native, help formats, as well as to output formats such as LaTeX, Postscript, RTF, etc. NOTE : All 16 and 32-bit words referenced in this document are stored in the database in Intel (least significant byte first) format. DATABASE HEADER typedef struct { char signature [8] ; unsigned short reader_version ; unsigned short database_version ; char sec_number_len ; char sec_title_len ; unsigned long flags ; unsigned short author_count ; unsigned short section_count ; unsigned short appendix_count ; unsigned short reference_count ; unsigned long title ; unsigned long title_length ; unsigned long copyright ; unsigned long copyright_length ; unsigned long authors ; unsigned long author_length ; unsigned long table_of_contents ; unsigned long table_of_contents_length ; unsigned long reference_index ; unsigned long reference_index_length ; unsigned long reference_string_length ; unsigned long references ; unsigned long reference_length ; } help_file_header ; char signature [8] ; Should be the string "POV-Help". Used for consistency check. unsigned short reader_version ; The version of the reader needed to read the database. Version 1.0 == 100. It is possible to have a newer database version that remains compatible with older readers. This is to indicate if the reader can handle the database. unsigned short database_version ; The version of the database. Version 1.0 == 100. char sec_number_len ; char sec_title_len ; These give the maximum length of the section number and title arrays later on in the database. Typically, these will be set to the length of the longest example of each of these that occurred in the input file that created the database. unsigned long flags ; Currently don't do much ; later on, will be used to indicate compression, etc. Also, will be used to indicate if the database was optimised for a specific platform, what sort of graphics are embedded, etc., etc. unsigned short author_count ; unsigned short section_count ; unsigned short appendix_count ; unsigned short reference_count ; The number, respectively, of o Author entries, o Sections, o Appendices, and o References in the database. unsigned long title ; unsigned long title_length ; The absolute offset of the title text in the database file, and its length. unsigned long copyright ; unsigned long copyright_length ; unsigned long authors ; unsigned long author_length ; Ditto for copyright and authors. unsigned long table_of_contents ; unsigned long table_of_contents_length ; The absolute offset of the table of contents entry in the database file. Also its length. unsigned long reference_index ; unsigned long reference_index_length ; Ditto for the reference index. unsigned long reference_string_length ; The length of each reference string in the reference index. Typically the length of the longest string. unsigned long references ; unsigned long reference_length ; The absolute offset of the reference array, and its length. General Overview. The help database consists of blocks of 'section text' - which are individually numbered subsections in the source, and include appendices - with embedded formatting and linking information. Each section can have links that point to one or several other sections. Users may browse these links. The Table of Contents (TOC) is an array of section numbers (strings) and section titles (strings again) the length of which is given in the header. Associated with each entry in the TOC is the absolute 32-bit offset of the relevant section in the database itself. typedef struct { unsigned long section ; unsigned long section_length ; char is_appendix ; char spare ; } TOC_entry ; Each entry in the TOC follows this format - the Section offset in the database, followed by the length of the section, followed by a flag indicating if the section is an appendix or not. Appendices are not treated very much differently from non-appendices ; the difference mainly relates to how they are presented to the ultimate user. NOTE : if your compiler pads structures out to word or double-word boundaries, be sure (when reading the data from the database) to read the correct amount of data, which is 10 bytes. (Though I suppose it won't hurt to read more, as long as you seek back to the correct location.) Immediately following the appendix flag is a character array whose length is given by the header field 'sec_number_len'. This field contains the ASCII representation of the section or appendix number, in the form '1.2.3', or 'E.1', for example. Only as many decimal points as needed are used. Immediately following the section number is the section title. Again, the length of this array is given in the header, by the field 'sec_title_len'. After this array, the next section entry starts, with no padding. Title The title is plain ASCII text, LF delimited. Authors The authors section is a sequence of LF delimited lines, NULL (0x00) separated between each author's entry. Copyright The copyright section is formatted in a fashion similar to that of the sections, using the same codes. However, hypertext links are not supported. References The Reference Index is an array of 32-bit double words which represent offsets into the database. At the location indicated by each offset is the actual variable-length reference represented by the index into the array of offsets. The reference itself is preceded by a 16-bit word known as the 'child count' which gives a count of actual targets for this index, minus one. Each target is represented by a 32-bit double word which gives the offset into the file of the targeted text. This may be at the start of or anywhere within a section or appendix. Typically, the first target will be the most important one and for systems that only support one target (or 'link') for each reference, this is the one to choose. Subsequent ones (if the child count is > 0) will be to other sections in the document which bear relation to the subject being referenced. Remember, the child count gives the number of targets minus one. That is to say, there is always at least one target (the 'parent') and any subsequent ones are 'children'. If the child count is 0, there are no children and only one 32-bit double word will be present. The section on 'Sections' gives more information on references. Sections The section text is a aggregation of ASCII text with special control codes embedded. Control codes are between 0xe0 and 0xff. LF characters only appear when a literal LF is required in the text (i.e. the CODE FRAGMENT or PRESERVE FORMATTING keywords were used in the source text.) Lines are 'long', i.e., they have had normal line feeds stripped out ; it is the help reader's job to wrap the lines properly for the output medium in use. Also embedded in the text are references and targets. A reference is a pointer to a target, a target is something that a reference points to. Targets can have multiple references pointing to them, and a single reference can have multiple targets. Take, for example, a reference to the word 'Sphere' in the POV-Ray documentation. The word 'sphere' would be highlighted at the location of the reference, indicating that link jumping is possible. If the user selects that reference, the reader would jump to the first target for that reference, which might be the definition of the 'Sphere' primitive. Any subsequent targets would be of lesser importance, perhaps other examples of the usage of that keyword. This is important, because some hypertext systems can only handle one target for each reference, and as such the author of the converter program has to be able to select the most appropriate target if more that one is defined. In the source of the document, each target has a 'priority'. This defaults to a given value, depending on the context, if one is not specified. After parsing the document, each target with the same name is first sorted in order of priority, and then in order of appearance. The author of the document would presumably make the most important target of the highest priority. All section and appendix titles and numbers are automatically made targets, and given a higher priority than the default. In the absence of an explicit override by the author, these targets will appear first in the list of targets. As well as being used for hypertext jumping, targets have their original ASCII names (as defined in the source text) stored in the database so that they may be used for keyword searches. (In the section text, targets are identified by index and not by name.) Currently, the sections have the concept of embedded line drawings. These are typically ASCII art and are delimited in the text so that an appropriate fixed- pitch font can be selected by the display program. At a later stage, these will go away and be replaced by a reference to the image database that will be bound into the help file. The original ASCII art will be found there, along with IBM line drawings, monochrome bitmaps, colour bitmaps, or whatever the author has defined in the source. The reader will be able to choose whichever is best for its particular output format. Embedded Codes If any code is escaped by the ESCAPE code, it loses any special meaning. Note that the 'ESCAPE' code referred to here is not an ASCII escape (0x1b) but the code defined in HELP.H as 'ESCAPE'. See HELP.H for the current definition of each code. These have changed since the first beta of POV-Help so make sure you've got a current database. [The old one has a different signature in its header so you'll know it.] BOLD_ON BOLD_OFF ITALIC_ON ITALIC_OFF HEADING_ON HEADING_OFF HIGHLIGHT_ON HIGHLIGHT_OFF UNDERSCORE_ON UNDERSCORE_OFF The above codes are used for formatting. For example, prior to a sentence that should appear in bold in the output, the BOLD_ON code will appear. When the bold text ends, the BOLD_OFF code shall appear. The heading code refers to a 'sub-heading' within a section. How you format it is up to you. You may like to centre the text if it is on a line of its own. Highlight means that he document author wants to show up the text given in a way other than bold, italic, or underline. Inverse text may be a good idea. NOTE : in the existing database, HIGHLIGHT is used extensively, whereas ITALIC and UNDERSCORE aren't used at all. This will change shortly, so please make sure you support them. I suggest you display or print highlight as bold with underscore, or whatever looks OK under the circumstance, until it is changed. [Most of the existing highlighted text will be replaced with bold/underscore.] LINE_ON LINE_OFF These relate to line drawings. They contain standard 7-bit ASCII characters, and need to be displayed or printed in a fixed-pitch font. CODE_ON CODE_OFF This delimits a code fragment, i.e., a fragment of source code or some such thing. They are no different to line drawings (in that their formatting needs to be preserved and that a fixed-pitch font needs to be used) but they are delimited as such because - 1) in printed text, different font conventions may be used for code, and 2) on-line help readers may give the option of pasting the code. For example, although it isn't documented, the ALT-TAB sequence in the DOS help reader will highlight the current code fragment. This is preparatory to allowing the code itself to be pasted via the keyboard buffer. PRESERVE_ON PRESERVE_OFF Preserve refers to 'preserve formatting', a catch-all for any other text in the source that needs to be displayed in a fixed-pitch font and for which no word- wrapping should be performed. In all of the above cases, a single LF will end a line of text. TABLE_ON TABLE_OFF Currently, Tables are just treated the same as PRESERVE, so please use them that way. Later on we may change that. Tables are intended for multi-column data that needs to be aligned in some special way. REFERENCE REFERENCE_ON REFERENCE_OFF The Reference code is followed by a 16-bit word giving the reference index. This value represents a index into the array of references as described earlier. When this appears in the text of a section, it means that the following word(s) (as delimited by REFERENCE_ON and REFERENCE_OFF) represent a link to the target given by the reference index. If the user highlights (or clicks on) the word(s), the help reader should jump to the first target. REFERENCE_ON and REFERENCE_OFF are used to delimit the text referred to by a previous REFERENCE, and an online help reader should display the text using whatever conventions exist for that particular platform. If the output medium is hard copy, and you want to be particularly clever, you may like to generate a reference to a footnote here, which in turn will provide a 'see section xxx on page yyy' type message. The difficulty here is in determining the page numbers in advance (if it is a forward jump) and that is left as an exercise for the reader. It may be necessary to scan the input file twice. Alternatively, if you know you are outputting to a file, you may like to enter dummy data and return later to fix it up with the real page. LIST_ON LIST_OFF LIST_ENTRY_ON LIST_ENTRY_OFF A List is considered a table with two columns - one with the list delimiters, and the other with the text. For example, all of these are lists - +Iname use alternate file name (default HELP.HLP) +N123 go to the 123rd section {/HIL/} (NOT section 123!) +S4.5.6 go to section '4.5.6' +Tsphere or "+Tsphere" go straight to the first section found with Up, Down move highlight bar Enter view selected item Escape exit help viewer * Standard include files that pre-define many shapes, colors and textures * Shapes can easily be combined to create new complex shapes. This feature is called Constructive Solid Geometry (CSG). POV-Ray supports unions, merges, intersections and differences in CSG. * Objects are assigned materials called textures. (A texture describes the coloring and surface properties of a shape.) As you can see, you need to know the length of the longest of the left part of the table so you know how far to indent the right. In the help database, the entire list will be bracketed with a LIST_ON and LIST_OFF. Immediately following the LIST_ON will be a single 8-bit value giving the number of character units to indent the right-hand column for that list. If you are using a proportional font, you may want to read the entire list to come up with a more appropriate value, rather than use the indent value times the maximum (or average) character width for the font you are using. The 'List Entry' is considered the left hand side of the table, i.e., the left column. Each of these (whether one single character or a whole sentence) is bracketed with a LIST_ENTRY_ON and LIST_ENTRY_OFF. Anything after a OFF is part of the right-hand column of the portion contained in the list entry. You should not find any line feeds in this text ; it is up to you to align it correctly. [Note that some beta versions of the database have a LF immediately after the length byte following the LIST_ON. This should be ignored.] PARAGRAPH A Paragraph code indicates the end of a paragraph. In the context of the help system, it is considered the same as a hard line feed followed by a blank line. More specifically, if the current character position is not at the left-hand side of the output medium, perform a LF. Then, in either case, perform another. INDENT The Indent code means you should indent the text following the code by whatever is considered the standard for your output medium. The indent should apply for the current line only ; that is, until the next LF or Paragraph code. TARGET The Target code delimits a location where a target exists. You don't really need to do anything about this, so just ignore them. CONVENTIONS Currently, there's no way to really tell what text belongs in which document. For example, the help database has instructions for using the DOS online help reader built in, and a FAQ at the end also. Obviously, you don't want to print that information on hardcopy. Later on, the database will include information that indicates the nature of each section so you can decide whether to include it or not. Properly, help for the online help reader should be built into it and not into the database, and eventually this will be the case. For now, though, use this convention - o ignore any section with a section number of less than 1.0. the help for the help reader has the section number 0.0. o optionally ignore any sections after a section that has the title 'FREQUENTLY ASKED QUESTIONS' as these are not part of POVRAY.DOC. EXAMPLES Please peruse the source of POVHELP.EXE for an example of an online help reader. POVHELP may be suitable for porting as it maintains its output in a virtual screen, the width and length of which can be set from the command line. Please also peruse the source of PHE2TXT.EXE. This is a program derived from POVHELP that reads the database and outputs a title, table of contents, and plain ASCII text sections in a page width of the users specification. This program keeps 'attributes' for each character according to bit flags defined in HELP.H, which define bold, underline, etc., but doesn't actually use them. This program may be suitable for porting as the basis of a hardcopy output converter, provided that the hardcopy uses fixed-pitch characters. PHE2RTF.C is a better (albeit not yet working) example of a converter. It has all the code needed to read the POV-Help database and issue the appropriate formatting codes ; the only problem with it is that the RTF it issues is not yet compatible with Microsoft Word. But that doesn't stop it being used as a basis of a converter to another format.